Skip to content

gh-151945: Fix reference warnings in http.cookiejar docs#152816

Merged
StanFromIreland merged 5 commits into
python:mainfrom
harjothkhara:gh-151945-cookiejar-refs
Jul 4, 2026
Merged

gh-151945: Fix reference warnings in http.cookiejar docs#152816
StanFromIreland merged 5 commits into
python:mainfrom
harjothkhara:gh-151945-cookiejar-refs

Conversation

@harjothkhara

Copy link
Copy Markdown
Contributor

Per @picnixz's suggestion in gh-151945, this covers the http.cookiejar
half of the issue; @picnixz is taking http.server.

Fixes the Sphinx nit-picky reference warnings for
Doc/library/http.cookiejar.rst and removes the file from
Doc/tools/.nitignore so future regressions are caught by CI.

  • Documented targets are qualified with their owning class, e.g.
    Cookie.version, CookiePolicy.rfc2965/hide_cookie2, the
    urllib.request.Request methods and attributes, and
    urllib.response.addinfourl.info.
  • The removed get_origin_req_host method, which has no documented
    target, becomes an inline literal.

Verified with a full nit-picky build: the file emits no warnings and
Doc/tools/check-warnings.py --fail-if-regression --fail-if-improved
passes. Documentation-only reference fix, so no NEWS entry (skip news).

Disclosure: I used AI assistance on this change; I've reviewed it and can
explain it.

Resolve the nit-picky reference warnings in Doc/library/http.cookiejar.rst
and drop the file from Doc/tools/.nitignore so future regressions are
caught by CI.

Documented targets are qualified with their owning class, for example
Cookie.version, CookiePolicy.rfc2965, the urllib.request.Request methods
and attributes, and urllib.response.addinfourl.info. References with no
documented target become inline literals: the removed get_origin_req_host
method.

The http.server part of the issue is left for a separate change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@read-the-docs-community

read-the-docs-community Bot commented Jul 1, 2026

Copy link
Copy Markdown

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Whilst we're here, please could also update the headers to use sentence case?

https://devguide.python.org/documentation/style-guide/#capitalization

That is, change the four "Objects" to "objects":

Image

Comment thread Doc/library/http.cookiejar.rst Outdated
Comment thread Doc/library/http.cookiejar.rst Outdated
Comment thread Doc/library/http.cookiejar.rst Outdated
Comment thread Doc/library/http.cookiejar.rst Outdated
@hugovk hugovk added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jul 2, 2026

@StanFromIreland StanFromIreland left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference fixes here are correct 👍 Please apply Hugo's suggestions.

…ge, markup

Apply Hugo's review feedback for Doc/library/http.cookiejar.rst:

- Use sentence case for the four "... Objects" section headers.
- Replace the Latin abbreviations "ie."/"eg." with "that is"/"for
  example" per the devguide simple-language guidance.
- Use ``None`` literal markup instead of :const:`None`.
- Reference the removed method as :meth:`!get_origin_req_host` to match
  the surrounding formatting.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@harjothkhara harjothkhara force-pushed the gh-151945-cookiejar-refs branch from 3945666 to 097e9ce Compare July 2, 2026 14:59
@harjothkhara

Copy link
Copy Markdown
Contributor Author

Thank you both! Applied all of Hugo's suggestions. Please re-review when you get a chance.

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@StanFromIreland StanFromIreland left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spotted two little things.

Comment thread Doc/library/http.cookiejar.rst Outdated
Comment thread Doc/library/http.cookiejar.rst Outdated
…self.filename

Apply Stan's review feedback:

- Point the response info() reference at http.client.HTTPResponse rather
  than the deprecated urllib.response.addinfourl.info.
- Keep the FileCookieJar.save attribute references as self.filename so
  they read clearly, using :attr:`!self.filename` to avoid a broken
  cross-reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Comment thread Doc/library/http.cookiejar.rst Outdated
Per Stan's suggestion, use the explicit-title cross-reference
:attr:`self.filename <FileCookieJar.filename>` so the text still reads
"self.filename" while linking to the documented attribute.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

@StanFromIreland StanFromIreland left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One little nit but otherwise LGTM, this is a solid improvement of the page. Thanks @harjothkhara and @claude.

Comment thread Doc/library/http.cookiejar.rst Outdated
@StanFromIreland StanFromIreland merged commit 66c76fa into python:main Jul 4, 2026
30 checks passed
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Jul 4, 2026
@miss-islington-app

Copy link
Copy Markdown

Thanks @harjothkhara for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

@StanFromIreland

Copy link
Copy Markdown
Member

Merged, thanks.

@bedevere-app

bedevere-app Bot commented Jul 4, 2026

Copy link
Copy Markdown

GH-153032 is a backport of this pull request to the 3.15 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 4, 2026
@miss-islington-app

Copy link
Copy Markdown

Sorry, @harjothkhara and @StanFromIreland, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 66c76fa6737d497cd3c735f75e67a5ca52eceb15 3.13

@bedevere-app

bedevere-app Bot commented Jul 4, 2026

Copy link
Copy Markdown

GH-153033 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 4, 2026
@bedevere-app

bedevere-app Bot commented Jul 4, 2026

Copy link
Copy Markdown

GH-153034 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Jul 4, 2026
StanFromIreland added a commit that referenced this pull request Jul 4, 2026
… the `http.cookiejar` docs (GH-152816) (#153033)

(cherry picked from commit 66c76fa)

Co-authored-by: Harjoth Khara <harjoth.khara@gmail.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
StanFromIreland added a commit that referenced this pull request Jul 4, 2026
… the `http.cookiejar` docs (GH-152816) (#153032)

(cherry picked from commit 66c76fa)

Co-authored-by: Harjoth Khara <harjoth.khara@gmail.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
StanFromIreland added a commit that referenced this pull request Jul 4, 2026
… the `http.cookiejar` docs (GH-152816) (#153034)

(cherry picked from commit 66c76fa)

Co-authored-by: Harjoth Khara <harjoth.khara@gmail.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

3 participants